home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 20 / Cream of the Crop 20 (Terry Blount) (1996).iso / program / recio214.zip / USAGE.TXT < prev   
Text File  |  1996-06-14  |  34KB  |  945 lines
  1.     Title: STANDARD USAGE OF C LANGUAGE RECIO LIBRARY
  2. Copyright: (C) 1994-1996, William Pierpoint
  3.   Version: 2.14
  4.      Date: June 14, 1996
  5.  
  6.  
  7.  
  8. 1.0 INTRODUCTION
  9.  
  10. The implementation descibed by this standard usage is a superset of the
  11. recio specification.  Enhancements are noted in the text.
  12.  
  13.  
  14. 1.1 Mnemonics
  15.  
  16. The recio functions have been given a consistent mnemonic naming
  17. convention.  All recio functions are in lower case and start with
  18. the letter r.  Function names are analogous to <stdio.h> functions.
  19. Mnemonics are as follows:
  20.  
  21. Single letter (field functions)               Multi-letter
  22. ----------------------------------------      -----------------
  23. b - base (prefix)                             beg - beginning
  24. c - column (prefix), character (suffix)       ch  - character
  25. d - double (suffix)                           col - column
  26. f - float (suffix)                            cxt - context
  27. i - integer (suffix)                          eof - end of file
  28. l - long (suffix)                             err - error
  29. n - number                                    fld - field buffer
  30. r - record pointer (first letter)             fmt - format  
  31. s - string pointer (suffix)                   fn  - function
  32. t - time_t time (suffix)                      no  - number         
  33. u - unsigned (suffix)                         num - number
  34.                                                 rec - record buffer  
  35.                           siz - size of buffer
  36.                           str - string
  37.                           tm  - struct tm time
  38.                           txt - text           
  39.  
  40. 1.2 Order
  41.  
  42. The order in which the prefix mnemonics appear indicates the order in which
  43. the arguments appear in the function.  The suffix mnemonics of the input
  44. functions tell you what the function returns.  The suffix mnemonics of the
  45. output functions indicate the last argument and tell you what the function
  46. outputs.  All output functions return an integer with a zero value if the
  47. function executed successfully.
  48.  
  49. For example, the input function rbgetui():
  50.  
  51.     arguments:  r - record pointer
  52.                 b - base (radix) of input
  53.       returns: ui - unsigned integer
  54.  
  55. The output function rbputui():
  56.  
  57.     arguments:  r - record pointer
  58.                 b - base (radix) of input
  59.                ui - unsigned integer is output
  60.  
  61. Note: c is used in the prefix of a function's name only once even if there are
  62.       two column arguments.  If the function inputs or outputs a character,
  63.       there is only one column argument; otherwise there are two.
  64.  
  65.  
  66.  
  67. 2.0 ERRORS AND WARNINGS
  68.  
  69. The functions declared in the header <recio.h> make use of the errno macro
  70. defined in section 4.1.3 of ANSI X3.159-1989.  This mechanism was chosen
  71. because (1) the <stdlib.h> conversion functions (strtod(), strtol(), etc.)
  72. make use of this error reporting mechanism and (2) the <recio.h> functions
  73. make use of the <stdlib.h> conversion functions.
  74.  
  75. In this implementation, errno can return the following macro constants:
  76.  
  77.          0 - No error.
  78.     EACCES - permission denied.
  79.       EDOM - argument out of domain.
  80.     EINVAL - invalid argument.
  81.     EMFILE - too many open files.
  82.     ENOENT - no such file or directory.
  83.     ENOMEM - out of memory.
  84.     ERANGE - out of range.
  85.  
  86. where
  87.  
  88. * EACCESS means that you don't have permission to access this file.  All
  89.   MSDOS files have read permission.
  90.  
  91. * EDOM says that the argument is ouside of the defined domain.  For 
  92.   example, if the days of the month are defined as 1 to 31 and you 
  93.   convert a string "1/32/1995" using sftotm(), an EDOM error will occur.
  94.  
  95. * EINVAL indicates an invalid argument to a function, usually a NULL record
  96.   pointer.  This is most often caused by a programming error.
  97.  
  98. * EMFILE means the program tried to open more files than the maximum allotted
  99.   by ROPEN_MAX or FOPEN_MAX.  If your program is interactive, the user can
  100.   close one or more open record streams.  Or you might decide that ROPEN_MAX
  101.   or FOPEN_MAX needs to be a larger value.
  102.  
  103. * ENOENT says that ropen() could not find the requested file to open.
  104.   Perhaps the name of the file was misspelled, or your program looked in
  105.   wrong directory.  If your program was trying to read a configuration file,
  106.   it could use internal default values when the configuration file does
  107.   not exist.
  108.  
  109. * ENOMEM indicates that the program ran out of heap space.  You may be able
  110.   to correct this if you are able to deallocate memory you no longer need.
  111.   For example, you could reduce the size of buffers when the size only
  112.   affects speed.  Such buffers need to be flushed first.  Buffers used by
  113.   the recio library do not fit this criteria.
  114.  
  115. * ERANGE tells you that the data is outside the capabilities of the data 
  116.   type to represent it.  The data value is either too large or too small.  
  117.   Either the data is incorrect or you need a more robust data type to hold 
  118.   the data.
  119.  
  120. Beginning with version 1.1, recio functions set errno when the record
  121. pointer is invalid and set an internal error number when the record pointer
  122. is valid.  The recio error number is accessed through the rerror function.
  123.  
  124. The rerror function can return the following macro constants:
  125.  
  126.          0 - No error.
  127.     R_EDOM - out of domain.
  128.   R_EINVAL - invalid argument (not the record pointer).
  129.  R_EINVDAT - invalid data.
  130.  R_EINVMOD - invalid mode.
  131.  R_EMISDAT - missing data.
  132.   R_ENOMEM - out of memory.
  133.   R_ENOPUT - unable to write data to output.
  134.   R_ERANGE - out of range.
  135.   R_EFAULT - application defined error.
  136.  
  137. where
  138.  
  139. * R_EDOM indicates an argument to a function is outside the defined 
  140.   domain.  For example, if base is defined to have a valid range of 
  141.   2 - 32 and you pass a 1, an R_EDOM error occurs.
  142.   
  143.   If the following conditions are not met, an R_EDOM error will result:
  144.   
  145.   Input of integral numbers:  2 <= base <= 32 or base==0
  146.   Output of integral numbers: 2 <= base <= 32
  147.   Input of time:              1 <= month <= 12
  148.                               1 <= day <= 31
  149.                               0 <= hour <= 23
  150.                               0 <= minute <= 59
  151.                               0 <= second <= 61 (includes 2 leap seconds)
  152.  
  153. * R_EINVDAT says the data is invalid.  Invalid data is caused by an
  154.   unrecognized character in the field.  For example, if you read an 
  155.   integral number that contained a letter, a R_EINVDAT error would 
  156.   occur.
  157.  
  158. * R_EINVMOD indicates that you opened a file in read mode, then used an 
  159.   output function or opened a file in write or append mode, then used an 
  160.   input function.
  161.  
  162. * R_EMISDAT says the data is missing.  Missing data means the field is empty.
  163.   If you expect a number, you could substitute either zero or some unique
  164.   number to indicate an empty field.
  165.  
  166. * R_ENOMEM indicates that the program ran out of heap space.  You may be able
  167.   to correct this if you are able to deallocate memory you no longer need.
  168.   For example, you could reduce the size of buffers when the size only
  169.   affects speed.  Such buffers need to be flushed first.  Buffers used by
  170.   the recio library do not fit this criteria.
  171.  
  172. * R_ENOPUT says the program was unable to write the data to the output.  
  173.   One possible cause is that the disk is full.
  174.  
  175. * R_ERANGE tells you that the data is outside the capabilities of the
  176.   data type to represent it.  For instance, suppose you used rgeti() 
  177.   to get an integer and the data value is 32768.  If a 16-bit integer 
  178.   has an upper limit of 32767, the value is too large.  If the data is 
  179.   wrong, you can have the error function correct it.  If the data is 
  180.   right, you need to correct the data type within the program.
  181.  
  182.   If the following types of data are not within the following ranges,
  183.   a R_ERANGE error will occur:
  184.   
  185.   integer: INT_MIN <= x <= INT_MAX
  186.   long: LONG_MIN <= x <= LONG_MAX
  187.   unsigned integer: 0 <= x <= UINT_MAX
  188.   unsigned long: 0 <= x <= ULONG_MAX
  189.   float: -FLT_MAX <= x <= -FLT_MIN or FLT_MIN <= x <= FLT_MAX or x==0.0
  190.   double: -DBL_MAX <= x <= -DBL_MIN or DBL_MIN <= x <= DBL_MAX or x==0.0
  191.   time_t: TIME_T_MIN <= x <= TIME_T_MAX
  192.  
  193. * R_EFAULT can be used with rseterr() in your own